<!--
        k2rt_documentation.html
        
        Copyright 2010 Beat Michel Liechti <liecb2@ebxliecb2>
        
        This program is free software; you can redistribute it and/or modify
        it under the terms of the GNU General Public License as published by
        the Free Software Foundation; either version 2 of the License, or
        (at your option) any later version.
        
        This program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.
        
        You should have received a copy of the GNU General Public License
        along with this program; if not, write to the Free Software
        Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
        MA 02110-1301, USA.
-->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
	<title>Dokumentation k2rtdev und k2rtapp</title>
	<meta http-equiv="content-type" content="text/html;charset=utf-8" />
	<meta name="generator" content="Geany 0.18" />
</head>

<body>
	<h1>Idee von k2rtdev und k2rtapp</h1>
	<p>
	Voraussetzung: Buchstabenrad, mit Auflösung 36 Impulse/U
	</p>
	<p>
	Das System besteht aus dem Xenomai Treiber k2rtdev und der 
	Xenomai Kommandozeilenapplikation k2rtapp. Die Applikation 
	fragt den Benutzer nach einem Text welcher auf dem Buchstabenrad 
	ausgegeben werden soll und nach der gewünschten Geschwindigkeit. 
	</p>
	<p>
	Nach der Eingabe wird der Text auf dem Rad ausgegeben indem Blitze im
	richtigen Moment ausgelöst werden. Jeder Buchstabe wird eine Sekunde 
	lang angezeigt, d.h. die Anzahl Blitze ist direkt von der Geschwindigkeit
	des Rades abhängig. Zusätzlich wird auch die Intensität des Stroboskops
	je nach Geschwindigkeit gesetzt und zwar nach der Formel 200 - USec:
	</p>
	<ul>
		<li>Geschwindigkeit 2 - Intensität 198</li>
		<li>Geschwindigkeit 100 - Intensität 100</li>
	</ul>    
	
	Dadurch wird die Helligkeit der Buchstaben angeglichen und bei hohen Tempi
	bleiben die Buchstaben scharf.
	
	<p>
		<code>
		Superfeature / Hack: Wird die Geschwindigkeit mit 0 angegeben so wird das Rad mit kurzen Impulsen
		bis zum entsprechenden Buchstaben gefahren. Da der Motor nicht abrupt gestoppt werden kann muss der
		Schwung des Rades beim Positionieren berücksichtigt werden. Wenn es mehrere Buchstaben sind dann 
		bleibt das Rad beim letzten Zeichen stehen. 
		</code>
	</p>
	
	<h1>Installation und Betrieb</h1>
	
	Bitte die Pfade an die Umgebung anpassen.
	<h3>Auf dem Host</h3>
	<ol>
		<li>sudo cp k2rtdev.ko /carme/rootfs/usr/local/bin</li>
		<li>sudo cp k2rtapp /carme/rootfs/usr/local/bin</li>
	</ol>
	<h3>Auf dem Board</h3>
	<ol>
		<li>cd /usr/local/bin</li>
		<li>insmod ./k2rtdev.ko</li>
		<li>export LD_LIBRARY_PATH=/usr/xenomai/lib</li>
		<li>./k2rtapp</li>
	</ol>

	<h1>Aufbau von k2rtdev (Treiber)</h1>
	
	Der Treiber registriert:
	<table border="1">
		<tr>
			<td>k2rtdev_open_nrt</td>
			<td>Öffnen des Treibers: Hier wird nichts gemacht</td>
			<td>Nicht Realtime</td>
		</tr>
		<tr>
			<td>k2rtdev_close_nrt</td>
			<td>Schliessen des Treibers: Hier wird nichts gemacht</td>
			<td>Nicht Realtime</td>
		</tr>
		<tr>
			<td>k2rtdev_ioctl_nrt</td>
			<td>Über IOCTL wird die Geschwindigkeit des Rades gesetzt</td>
			<td>Nicht Realtime</td>
		</tr>
		<tr>
			<td>k2rtdev_write_rt</td>
			<td>Über Write wird der Text den der Treiber ausgeben soll übergeben. 
			Die Funktion setzt für jeden Buchstaben einen Countdownzähler und den entsprechenden 
			Positionszähler. Der Countdownzähler (showcount) gibt die Anzahl Blitze an welche ausgelöst 
			werden um den Buchstaben eine Sekunde lang zu beleuchten. Der Positionszähler (rotary)
			gibt die Position des Buchstabens auf der Scheibe an. Dann wird auf einen Event 
			gewartet der signalisiert dass der Buchstabe geschrieben wurde.</td>
			<td>Realtime</td>
		</tr>
		<tr>
			<td>index_irq_handler_rt</td>
			<td>Der Interrupthandler wird bei jedem Nulldurchgang aufgerufen. Er setzt den
			Positionszähler (rotary) wieder auf 0 zurück</td>
			<td>Realtime</td>
		</tr>
		<tr>
			<td>rotary_irq_handler_rt</td>
			<td>Der Interrupthandler wird bei jedem Inkrement der Scheibe aufgerufen, d.h. 
			in diesem Fall 36 Mal pro Umdrehung. Bei jedem Aufruf wird der Positionszähler
			um 1 inkrementiert. Wenn nun der Positionszähler dem gewünschten Buchstaben 
			entspricht und der Countdownzähler grösser 0 ist dann wird der Blitz ausgelöst 
			und der Countdownzähler um 1 dekrementiert. Ist der Countdownzähler bei 0 angelagt
			dann wird ein Event ausgelöst um zu signalisieren dass der Buchstabe geschrieben worden ist. </td>
			<td>Realtime</td>
		</tr>
	</table>
	
	<h1>Aufbau von k2rtapp (Applikation)</h1>
	
	Die Applikation fragt Text und Geschwindigkeit ab. Dann wird das Gerät mit rt_dev_open geöffnet, 
	die Geschwindigkeit des Rades über rt_dev_ioctl gesetzt, der Text mit rt_dev_write an den Treiber
	übergeben und danach wird das Rad mit rt_dev_ioctl wieder gestoppt (Geschwindigkeit = 0).
	
	<h1>Latenzzeitmessungen</h1>
	Der Blitz wurde in allen Fällen beim Nulldurchgang direkt durch den Interrupthandler ausgelöst. 
	<table border="1">
		<tr>
			<td valign="top">
				<h2>Non-Xenomai - Speed 100 - mit wenig Last</h2>
				Auch bei einem Nicht-Xenomai Treiber können sehr gute Latenzzeiten 
				erreicht werden wenn das System wenig Last hat. In diesem Fall wurden 
				neben der Kaffemaschinenapplikation noch Soundclips mit mplayer
				abgespielt. Alles bleibt im Bereich von 5-35 &mu;S.
			</td>
			<td><img src="lll5.jpeg"></td>
		</tr>
		<tr>
			<td valign="top">
				<h2>Xenomai - Speed 100 - ohne Last</h2>
				Der Xenomai Treiber hat im besten Fall eine etwas grössere Latenzzeit als der 
				Nicht-Xenomai Treiber (10 &mu;S). Hier ist überhaupt keine Last auf dem System 
				und es gibt fast keine Ausreisser. Alles bleibt im Bereich von 10-22 &mu;S.
			</td>
			
			<td><img src="lll6.jpeg"></td>
		</tr>
		<tr>
			<td valign="top">
				<h2>Non-Xenomai - Speed 100 - mit Last</h2>
				Bei Last zeigt sich dass beim Nicht-Xenomai Treiber gravierende Ausreisser
				entstehen können, hier 70 &mu;S und mehr. 
			</td>
			<td><img src="lll4.jpeg"></td>
		</tr>
		<tr>
			<td valign="top">
				<h2>Xenomai - Speed 100 - mit Last</h2>
				Der Xenomai Treiber kann auch unter Last eine gute Latenzzeit garantieren
				und es zeigen sich keine Ausreisser. Alles bleibt im Bereich von 10-28 &mu;S
				also im schlechtesten Fall nur 6 &mu;S mehr als ohne Last.
			</td>
			<td><img src="lll7.jpeg"></td>
		</tr>
	</table>
	
</body>
</html>
